home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Libraries / C Internet Config / IC Headers ƒ / IC API Descriptions.h < prev    next >
Encoding:
Text File  |  1995-11-17  |  21.4 KB  |  182 lines  |  [TEXT/SPM ]
  1.  such a pair, it implicitly
  2.     calls ICBegin(inst, icReadOnlyPerm).
  3.     This routine is now obsolete. Use ICFindPrefHandle instead.
  4.     Reads the preference specified by key from the IC database into
  5.     a newly created handle, prefh.
  6.     key must not be the empty string.
  7.     attr is set to the attributes associated with the preference.
  8.     The incoming value of prefh is ignored.
  9.     A new handle is created in the current heap and returned in prefh.
  10.     If the routine returns an error, prefh is set to nil.
  11.     If the preference does not exist, no error is returned and prefh is set
  12.     to an empty handle.
  13. */
  14.  
  15. ICError ICSetPrefHandle(ICInstance inst,StringPtr key,ICAttr attr,Handle prefh);
  16. /*
  17.     Requires IC 1.1.
  18.     You must specify a configuration before calling this routine.
  19.     If you are getting or setting multiple preferences, you should place
  20.     these calls within an ICBegin/ICEnd pair.
  21.     If you call this routine outside of such a pair, it implicitly
  22.     calls ICBegin(inst, icReadWritePerm).
  23.     Sets the preference specified by key from the IC database to the
  24.     value contained in prefh.
  25.     key must not be the empty string.
  26.     If prefh is nil then the preference value is not set.
  27.     If buf is not nil then the preference value is set to the data
  28.     contained in it.
  29.     If attr is ICattr_no_change then the preference attributes are not set.
  30.     Otherwise the preference attributes are set to attr.
  31.     Returns icPermErr if the previous ICBegin was passed icReadOnlyPerm.
  32.     Returns icPermErr if current attr is locked, new attr is locked and prefh <> nil.
  33. */
  34.  
  35. ICError ICCountPref(ICInstance inst,long* count);
  36. /*
  37.     You must specify a configuration before calling this routine.
  38.     You must be inside an ICBegin/End pair to call this routine.
  39.     Counts the total number of preferences.
  40.     If the routine returns an error, count is set to 0.
  41. */
  42.  
  43. ICError ICGetIndPref(ICInstance inst,long n,StringPtr key);
  44. /*
  45.     You must specify a configuration before calling this routine.
  46.     You must be inside an ICBegin/End pair to call this routine.
  47.     Returns the key of the Nth preference.
  48.     n must be positive.
  49.     Returns icPrefNotFoundErr if n is greater than the total number of preferences.
  50.     If the routine returns an error, key is undefined.
  51. */
  52.  
  53. ICError ICDeletePref(ICInstance inst,StringPtr key);
  54. /*
  55.     You must specify a configuration before calling this routine.
  56.     You must be inside an ICBegin/End pair to call this routine.
  57.     Deletes the preference specified by key.
  58.     key must not be the empty string.
  59.     Returns icPrefNotFound if the preference specified by key is not present.
  60. */
  61.  
  62. ICError ICEnd(ICInstance inst);
  63. /*
  64.     You must specify a configuration before calling this routine.
  65.     You must be inside an ICBegin/End pair to call this routine.
  66.     Terminates a preference session, as started by ICBegin.
  67.     You must have called ICBegin before calling this routine.
  68. */
  69.  
  70. /* ***** User Interface Stuff ***** */
  71.  
  72. ICError ICEditPreferences(ICInstance inst,StringPtr key);
  73. /*
  74.     Requires IC 1.1.
  75.     You must specify a configuration before calling this routine.
  76.     You do not have to be inside an ICBegin/End pair to call this routine.
  77.     Instructs IC to display the user interface associated with editing
  78.     preferences and focusing on the preference specified by key.
  79.     If key is the empty string then no preference should be focused upon.
  80.     You must have specified a configuration before calling this routine.
  81.     You do not need to call ICBegin before calling this routine.
  82.     In the current implementation this launches the IC application
  83.     (or brings it to the front) and displays the window containing
  84.     the preference specified by key.
  85.     It may have a radically different implementation in future
  86.     IC systems.
  87. */
  88.  
  89. /* ***** URL Handling ***** */
  90.  
  91. ICError ICParseURL(ICInstance inst,StringPtr hint,Ptr data,long len,long* selStart,long* selEnd,Handle url);
  92. /*
  93.     Requires IC 1.1.
  94.     You must specify a configuration before calling this routine.
  95.     You do not have to be inside an ICBegin/End pair to call this routine.
  96.     Parses a URL out of the specified text and returns it in a canonical form
  97.     in a handle.
  98.     hint indicates the default scheme for URLs of the form "name@address".
  99.     If hint is the empng
  100.     file and returns the most appropriate mappings database entry.
  101.     entries must be a handle to a valid IC mappings database preference.
  102.     The filename may be either the name of the outgoing file or
  103.     the empty string.
  104.     Returns icPrefNotFoundErr if no suitable entry found.
  105. */
  106.  
  107. /* ----- Low Level Routines ----- */
  108.  
  109. ICError ICCountMapEntries(ICInstance inst,Handle entries,long* count);
  110. /*
  111.     Requires IC 1.1.
  112.     You must specify a configuration before calling this routine.
  113.     You do not have to be inside an ICBegin/End pair to call this routine.
  114.     Counts the number of entries in the mappings database.
  115.     entries must be a handle to a valid IC mappings database preference.
  116.     count is set to the number of entries.
  117. */
  118.  
  119. ICError ICGetIndMapEntry(ICInstance inst,Handle entries,long ndx,long* pos,ICMapEntry* entry);
  120. /*
  121.     Requires IC 1.1.
  122.     You must specify a configuration before calling this routine.
  123.     You do not have to be inside an ICBegin/End pair to call this routine.
  124.     Gets the ndx'th entry in the mappings database.
  125.     entries must be a handle to a valid IC mappings database preference.
  126.     ndx must be in the range from 1 to the number of entries in the database.
  127.     The value of pos is ignored on input. pos is set to the position of
  128.     the ndx'th entry in the database and is suitable for passing back
  129.     into ICSetMapEntry.
  130.     Does not return any user data associated with the entry.
  131. */
  132.  
  133. ICError ICGetMapEntry(ICInstance inst,Handle entries,long pos,ICMapEntry* entry);
  134. /*
  135.     Requires IC 1.1.
  136.     You must specify a configuration before calling this routine.
  137.     You do not have to be inside an ICBegin/End pair to call this routine.
  138.     Returns the entry located at position pos in the mappings database.
  139.     entries must be a handle to a valid IC mappings database preference.
  140.     pos should be 0 to get the first entry. To get the subsequent entries, add
  141.     entry.total_size to pos and iterate.
  142.     Does not return any user data associated with the entry.
  143. */
  144.  
  145. ICError ICSetMapEntry(ICInstance inst,Handle entries,long pos,ICMapEntry* entry);
  146. /*
  147.     Requires IC 1.1.
  148.     You must specify a configuration before calling this routine.
  149.     You do not have to be inside an ICBegin/End pair to call this routine.
  150.     Sets the entry located at position pos in the mappings database.
  151.     entries must be a handle to a valid IC mappings database preference.
  152.     pos should be either a value returned from ICGetIndMapEntry or a value
  153.     calculated using ICGetMapEntry.
  154.     entry is a var parameter purely for stack space reasons. It is not
  155.     modified in any way.
  156.     Any user data associated with the entry is unmodified.
  157. */
  158.  
  159. ICError ICDeleteMapEntry(ICInstance inst,Handle entries,long pos);
  160. /*
  161.     Requires IC 1.1.
  162.     You must specify a configuration before calling this routine.
  163.     You do not have to be inside an ICBegin/End pair to call this routine.
  164.     Deletes the mappings database entry at pos.
  165.     entries must be a handle to a valid IC mappings database preference.
  166.     pos should be either a value returned from ICGetIndMapEntry or a value
  167.     calculated using ICGetMapEntry.
  168.     Also deletes any user data associated with the entry.
  169. */
  170.  
  171. ICError ICAddMapEntry(ICInstance inst,Handle entries,ICMapEntry* entry);
  172. /*
  173.     Requires IC 1.1.
  174.     You must specify a configuration before calling this routine.
  175.     You do not have to be inside an ICBegin/End pair to call this routine.
  176.     Adds an entry to the mappings database.
  177.     entries must be a handle to a valid IC mappings database preference.
  178.     The entry is added to the end of the entries database.
  179.     No user data is added.
  180. */
  181. #endif
  182.